home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
Amiga Plus Special 16
/
AMIGAplus Sonderheft 16 (1998)(ICP)(DE)[!].iso
/
pd
/
anwendungen
/
madhouse
/
developer
/
autodocs
/
madblankersupport.doc
Wrap
Text File
|
1998-02-04
|
21KB
|
783 lines
TABLE OF CONTENTS
madblankersupport.library/--overview--
madblankersupport.library/MBS_AllocPalette
madblankersupport.library/MBS_BeginAutoCycling
madblankersupport.library/MBS_ClearMousePointer
madblankersupport.library/MBS_ColorCycleStep
madblankersupport.library/MBS_ContinueBlanking
madblankersupport.library/MBS_DebugMode
madblankersupport.library/MBS_EndAutoCycling
madblankersupport.library/MBS_ErrorReport
madblankersupport.library/MBS_FreePalette
madblankersupport.library/MBS_GetBlankjob
madblankersupport.library/MBS_GetColorPrefs
madblankersupport.library/MBS_GetFontPrefs
madblankersupport.library/MBS_GetPaletteColor
madblankersupport.library/MBS_GetPrefs
madblankersupport.library/MBS_GetScreenmodePrefs
madblankersupport.library/MBS_GetScreenmodePrefs
madblankersupport.library/MBS_GetScreenPalette
madblankersupport.library/MBS_GetStringPrefs
madblankersupport.library/MBS_PaletteSpread
madblankersupport.library/MBS_PutPaletteColor
madblankersupport.library/MBS_Quit
madblankersupport.library/MBS_RefreshPalette
madblankersupport.library/MBS_SetPaletteScreen
madblankersupport.library/--overview-- madblankersupport.library/--overview--
NAME
--overview-- -- overview
SYNOPSIS
--overview--();
void --overview-- (void);
NOTE
madblankersupport.library is used for all blanker communication with
Madhouse. Please note that some functions have to be called in a
special order:
- Open the library. Please use the latest version.
- Call MBS_DebugMode() if you want to run the blanker yourself,
delete this call when compiling a blanker for Madhouse.
- Call MBS_GetBlankjob().
- Call any other function. Maybe you first want to get the blanker's
settings using MBS_GetPrefs() and others.
- Open your screen. You could do that before, but hopefully the
screen mode is configurable, so you have to
MBS_GetScreenmodePrefs() first.
- Main loop. Draw graphics and so on... ask MBS_ContinueBlanking()
for a result !=0, which means that you have to exit the main loop.
- Close your screen.
- Call MBS_Quit() after closing the screen.
- Close the library and all other stuff.
SEE ALSO
MBS_DebugMode(), MBS_GetBlankjob(), MBS_GetPrefs(),
MBS_ContinueBlanking(), MBS_Quit()
madblankersupport.library/MBS_AllocPalette
NAME
MBS_AllocPalette -- Allocate an internal palette structure. (V26)
SYNOPSIS
palette = MBS_AllocPalette();
d0
APTR MBS_AllocPalette (void);
FUNCTION
You can manipulate this palette using the supplied functions. They
all feature the OS 2.x 4bit per gun definition and the OS 3.x 32bit
per gun definition transparently, taking a lot of problems off your
shoulders.
RESULT
palette (d0) - black box pointer to the internal palette. May be
NULL if there is not enough memory available.
SEE ALSO
MBS_FreePalette(), MBS_SetPaletteScreen()
madblankersupport.library/MBS_BeginAutoCycling
NAME
MBS_BeginAutoCycling -- Starts automatic color cycling, using a
detached Process. (V26)
SYNOPSIS
MBS_BeginAutoCycling( palette, start, end, direction, steps, delay );
a2 a1 a0 d2 d1 d0
void MBS_BeginAutoCycling( APTR palette, LONG start, LONG end, LONG
direction, LONG steps, LONG delay );
FUNCTION
Color cycling goes without further triggering from the blanker task
and can be stopped using MBS_EndAutoCycling(). The blanker process
and a color cycling process will run simultaneously.
INPUTS
palette - pointer to the internal palette.
start - the first palette entry to be cycled (inclusive).
end - the last palette entry to be cycled (inclusive). Note that
start < end is required.
direction - for incremental color cycling, use 1. Any other input
will result in decremental cycling (backwards).
steps - when using a higher number that 1, more steps than one will
be done with one function call of MBS_ColorCycleStep(). This
function is called from the detached Process.
delay - delay in 1/50s between two cycling events. (Delay() will be
called.)
WARNING
Stop this effect before closing the screen!
Do not use other color manipulating/cycling functions before doing an
MBS_EndAutoCycling()!
SEE ALSO
MBS_EndAutoCycling()
madblankersupport.library/MBS_ClearMousePointer
NAME
MBS_ClearMousePointer -- Lets the mouse cursor vanish.
SYNOPSIS
MBS_ClearMousePointer( screen );
d0
void MBS_ClearMousePointer( struct Screen *screen );
FUNCTION
Set an empty mouse pointer image on all windows currently opened on
the screen.
INPUTS
screen - pointer to struct Screen of the screen which should get its
mouse pointer erased.
madblankersupport.library/MBS_ColorCycleStep
NAME
MBS_ColorCycleStep -- cycles your palette one step and displays it.
(V26)
SYNOPSIS
MBS_ColorCycleStep( palette, start, end, direction, steps );
a1 a0 d2 d1 d0
void MBS_ColorCycleStep( APTR palette, LONG start, LONG end, LONG
direction, LONG steps );
FUNCTION
This will color-cycle your palette. A LoadRBG4/32 call will be done,
so you'll see the results directly after the call of this function.
INPUTS
palette - pointer to the internal palette
start - the first palette entry to be cycled (inclusive)
end - the last palette entry to be cycled (inclusive). Note that
start < end is required.
direction - for incremental color cycling, use 1. Any other input
will result in decremental cycling (backwards).
steps - when using a higher number that 1, more steps than one will
be done with one function call of MBS_ColorCycleStep().
SEE ALSO
MBS_BeginAutoCycling()
madblankersupport.library/MBS_ContinueBlanking
NAME
MBS_ContinueBlanking -- Get server blanking state.
SYNOPSIS
continue = MBS_ContinueBlanking();
D0
LONG MBS_ContinueBlanking (void);
FUNCTION
You should ask MBS_ContinueBlanking() very often, maybe even in a
tight loop. Experiment with exit speeds. Return values:
- MBSCB_CONTINUE (0) -- Just continue.
- MBSCB_TIMEOUT (1) -- The user has set a `duration' for your
Blanker, this time is now expired. The blanker may continue for
some seconds, maybe to finish an effect. As an example, the Soccer
blanker moves all players out of view.
- MBSCB_USERABORT (2) -- Abort as fast as possible, a user defined
event (e.g. a mouse click) has happened.
RESULT
continue (D0) - Continue state, to be asked in a blanker's main loop.
At the moment, three results are possible, a result of 0 will
always mean that the blanker can continue.
NOTE
When running in Debug Mode, only mouse clicks are considered an
event, and timeout is after 120 seconds.
(v27.7) CTRL_C signal is checked, also. MSCB_USERABORT will be
returned in case the signal is set. This is useful for debugging
(Madhouse)...
SEE ALSO
MBS_DebugMode()
madblankersupport.library/MBS_DebugMode
NAME
MBS_DebugMode -- run blanker in Debug Mode
SYNOPSIS
MBS_DebugMode();
void MBS_DebugMode (void);
FUNCTION
Without using that function, you cannot simply run your blanker
executable out of a shell. Preferences file and Madhouse server
aren't granted in that situation. To test your blanker in a
programming environment, call MBS_DebugMode() before
MBS_GetBlankjob(). This will have the following effects:
- Default values are passed in MBS_GetPrefs().
- Locale language is "english".
- Duration time is 120 seconds.
NOTE
Madhouse cannot run your blanker with a MBS_DebugMode() call in it!
Don't forget to remove it before you put your blanker executable in
its Madhouse blanker subdirectory.
BUGS
This function throws Enforcer hits.
SEE ALSO
MBS_GetBlankjob(), MBS_GetPrefs()
madblankersupport.library/MBS_EndAutoCycling
NAME
MBS_EndAutoCycling -- stops the automatic color cycling. (V26)
SYNOPSIS
MBS_EndAutoCycling();
void MBS_EndAutoCycling (void);
WARNING
Call this function before closing your screen!
madblankersupport.library/MBS_ErrorReport
NAME
MBS_ErrorReport -- Inform Madhouse about an error situation. Give
feedback to the user.
SYNOPSIS
MBS_ErrorReport( text );
d0
void MBS_ErrorReport( char *text );
FUNCTION
Madhouse will display your text in an EasyRequester after the user
aborted your blanker or another one (if your blanker exited because
of the error situation). The name of your blanker will be displayed
in that requester, too.
INPUTS
text - Pointer to an error text string, max. 500 bytes long. A copy
of your string will be kept internally. Use '\n' to insert
line feeds.
NOTE
Calling this function twice will cause the second text to remain.
This works global for all started blankers: if a second blanker
throws an error report, too, you'll see the report of the second
blanker.
madblankersupport.library/MBS_FreePalette
NAME
MBS_FreePalette -- free an internal palette. (V26)
INPUTS
palette - black box pointer you got in MBS_AllocPalette().
madblankersupport.library/MBS_GetBlankjob
NAME
MBS_GetBlankjob -- Signal Blanker task activity and get some basic
information.
SYNOPSIS
blankjob = MBS_GetBlankjob();
D0
mbs_blankjob *MBS_GetBlankjob (void);
FUNCTION
Madhouse gets signaled that your blanker task is happy, up and
running. It runs the stopwatch for your blanker and fills the
mbs_blankjob structure. It arranges Message Ports for communication
with Madhouse, and so on.
(v27.7) SigAlloc() is called to receive SIGBREAKF_CTRL_C.
RESULT
blankjob (D0) - Pointer to read-only data. Maybe you don't want to
store this result at all, no library function needs it. You
don't have to expect a NULL result. You can use it to obtain
the locale language (for error messages) or the
user-predefined blanking time (if you want your effect to
`fade out' just before Madhouse tells the blanker to stop
because of timeout).
WARNING
You have to call this function, before calling any other support
function. You should call it directly after opening this library.
EXCEPTION: If you want to run your blanker yourself (this is called
Debug Mode), you have to call MBS_DebugMode() BEFORE MBS_BlankJob().
SEE ALSO
MBS_DebugMode(), MBS_Quit()
madblankersupport.library/MBS_GetColorPrefs
NAME
MBS_GetColorPrefs -- Get a color preference item, as defined in
gadget file.
SYNOPSIS
MBS_GetColorPrefs( ID, storage );
a0 d0
void MBS_GetColorPrefs( char *ID, mbs_color *storage );
FUNCTION
Obtain preferences information from Madhouse. You can call this
function any time between MBS_GetBlankjob() and MBS_Quit(), no matter
how often.
INPUTS
ID - Identifier string, should equal one of the gadget identifiers
used in the blanker's gadget file. String comparison is not
case sensitive.
storage - Pass on a pointer to an initialized mbs_color struct here.
Data will be overwritten, except when running in Debug Mode
or no `pref' is file found.
EXAMPLE
in source code:
struct mbs_color col;
col.r = 255;
col.g = 200;
col.b = 0;
MBS_GetColorPrefs( "background", &col );
in gadget file:
background = Color,
SEE ALSO
MBS_GetBlankjob(), MBS_Quit()
madblankersupport.library/MBS_GetFontPrefs
NAME
MBS_GetFontPrefs -- Get a font preference item, as defined in gadget
file.
SYNOPSIS
MBS_GetFontPrefs( ID, textat, buffer );
a0 d1 d0
void MBS_GetFontPrefs( char *ID, struct TextAttr *textat, char
*buffer );
FUNCTION
Obtain preferences information from Madhouse. You can call this
function any time between MBS_GetBlankjob() and MBS_Quit(), no matter
how often.
INPUTS
ID - Identifier string, should equal one of the gadget identifiers
used in the blanker's gadget file. String comparison is not
case sensitive.
textat - Pass on a pointer to an initialized struct TextAttr here.
ta_Name and ta_YSize will be filled in, except when running
in Debug Mode or no `pref' is file found. ta_Name will point
to the given `buffer'.
buffer - Pass on a pointer to your (at least 100 bytes long) buffer
array. The font name will be filled in here, ".font" will be
added. textat.ta_Name will point to this buffer. Therefore,
you should have the buffer in a global variable (or use
"static").
EXAMPLE
in source code:
char buf[100];
strcpy( buf, "topaz.font" );
struct TextAttr ta;
ta.ta_Name = buf;
ta.ta_YSize = 8;
ta.ta_Style = 0;
ta.ta_Flags = 0;
MBS_GetFontPrefs( "font", &ta, buf );
in gadget file:
font = Font( "f" ),
SEE ALSO
MBS_GetBlankjob(), MBS_Quit()
madblankersupport.library/MBS_GetPaletteColor
NAME
MBS_GetPaletteColor -- Get a single color register of the internal
palette. (V26)
INPUTS
palette - pointer to the internal palette
position - register number to get the color from, counted from 0.
color - pointer to a struct color which r,g,b elements will be
overwritten.
madblankersupport.library/MBS_GetPrefs madblankersupport.library/MBS_GetPrefs
NAME
MBS_GetPrefs -- Get a numeric preference item, as defined in gadget
file.
SYNOPSIS
prefvalue = MBS_GetPrefs( ID, default );
d0 a0 d0
LONG MBS_GetPrefs( char *ID, LONG default );
FUNCTION
Obtain preferences information from Madhouse. You can call this
function any time between MBS_GetBlankjob() and MBS_Quit(), no matter
how often.
INPUTS
ID - Identifier string, should equal one of the gadget identifiers
used in the blanker's gadget file. String comparison is not
case sensitive.
default - Default value. Used if no `pref' file found or running in
Debug Mode.
RESULT
prefvalue (d0) - numeric pref value, e.g. the state of a cycle
gadget (counted beginning with 0) or a slider or a checkmark
gadget. The default is maybe passed on (s.a.).
EXAMPLE
in source code:
LONG speed = MBS_GetPrefs( "speed", 3 );
in gadget file:
speed = Slider( "s", 1, 5 ),
SEE ALSO
MBS_GetBlankjob(), MBS_Quit()
madblankersupport.library/MBS_GetScreenmodePrefs
NAME
MBS_GetScreenmodePrefs -- Get the screen depth of the user selected
screen mode.
SYNOPSIS
depth = MBS_GetScreenmodePrefs( default );
d0 d0
ULONG MBS_GetScreenmodePrefs( ULONG default );
FUNCTION
Obtain preferences information from Madhouse. You can call this
function any time between MBS_GetBlankjob() and MBS_Quit(), no matter
how often.
INPUTS
default - default screen depth. Used if no `pref' file found or
running in Debug Mode. May range from 1 to 8.
RESULT
depth (d0) - selected screen depth. `default' may be passed on. May
range from 0 to 8. (0 means that you didn't want a user
selectable screen depth in your blanker's `gadget' file.)
NOTE
The screen depth preferences has no identifier. Only one value can
be set in MadhouseConfigEd and stored in the `pref' file.
EXAMPLE
in source code:
ULONG depth = MBS_GetScreendepthPrefs( 3 );
in gadget file:
DisplayMode( 3 ),
3 is default amount of bitplanes. If you don't want a
user selectable screen depth, use:
DisplayMode( 0 ),
SEE ALSO
MBS_GetScreenmodePrefs(), MBS_GetBlankjob(), MBS_Quit()
madblankersupport.library/MBS_GetScreenmodePrefs
NAME
MBS_GetScreenmodePrefs -- Get the Screen Mode ID of the user selected
display mode.
SYNOPSIS
ModeID = MBS_GetScreenmodePrefs( default );
d0 d0
ULONG MBS_GetScreenmodePrefs( ULONG default );
FUNCTION
Obtain preferences information from Madhouse. You can call this
function any time between MBS_GetBlankjob() and MBS_Quit(), no matter
how often.
INPUTS
default - Default Mode ID. Used if no `pref' file found or running
in Debug Mode.
RESULT
ModeID (d0) - selected display mode. `default' may be passed on.
NOTE
The Screen Mode preferences has no identifier. Only one mode can be
set in MadhouseConfigEd and stored in the `pref' file.
EXAMPLE
in source code:
ULONG modeID = MBS_GetScreenmodePrefs( HIRESLACE_KEY );
in gadget file:
DisplayMode( 3 ),
3 is default amount of bitplanes. If you don't want a
user selectable screen depth, use:
DisplayMode( 0 ),
SEE ALSO
MBS_GetBlankjob(), MBS_Quit()
madblankersupport.library/MBS_GetScreenPalette
NAME
MBS_GetScreenPalette -- copy the screen's palette to the internal
palette. (V26)
SYNOPSIS
MBS_GetScreenPalette( palette, screen );
a0 d0
void MBS_GetScreenPalette( APTR palette, struct Screen *screen );
FUNCTION
The internal palette will be filled with the color data of the given
screen. Useful for blankers which copy a screen to make effects on
the Workbench.
INPUTS
palette - pointer to the internal palette
screen - screen to get the palette information from
NOTE
This function will perform an MBS_SetPaletteScreen() call with the
given screen as an argument. If you pass a screen that is not yours,
call MBS_SetPaletteScreen() will your own screen afterwards.
madblankersupport.library/MBS_GetStringPrefs
NAME
MBS_GetStringPrefs -- Get a text string preference item, as defined
in gadget file.
SYNOPSIS
MBS_GetStringPrefs( ID, storage );
a0 d0
void MBS_GetStringPrefs( char *ID, char *storage );
FUNCTION
Obtain preferences information from Madhouse. You can call this
function any time between MBS_GetBlankjob() and MBS_Quit(), no matter
how often.
INPUTS
ID - Identifier string, should equal one of the gadget identifiers
used in the blanker's gadget file. String comparison is not
case sensitive.
storage - Pass on a pointer to an initialized array of char here.
Data will be overwritten, except when running in Debug Mode
or no `pref' is file found. Make the array big enough so
that the string fits (maximum string length is defined in
`gadget' file).
EXAMPLE
in source code:
char text[150];
strcpy( text, "Oh, what a night!" );
MBS_GetStringPrefs( "message", text );
in gadget file:
message = String( "m", 150 ),
SEE ALSO
MBS_GetBlankjob(), MBS_Quit()
madblankersupport.library/MBS_PaletteSpread
NAME
MBS_PaletteSpread -- Make a spread between two palette registers.
(V26)
SYNOPSIS
MBS_PaletteSpread( palette, start, stop );
a0 d1 d0
void MBS_PaletteSpread( APTR palette, LONG start, LONG stop );
FUNCTION
An RGB color spread will be generated in between the given register
numbers.
INPUTS
palette - pointer to the internal palette.
start - first color of the spread.
stop - second color of the spread.
NOTE
Take care: start <= stop.
This won't change anything onscreen, since the palette isn't updated
automatically.
SEE ALSO
MBS_RefreshPalette()
madblankersupport.library/MBS_PutPaletteColor
NAME
MBS_PutPaletteColor -- Set a single color register of the internal
palette. (V26)
SYNOPSIS
MBS_PutPaletteColor( palette, position, color );
a0 d1 d0
void MBS_PutPaletteColor( APTR palette, LONG position, struct
mbs_color *color );
INPUTS
palette - pointer to the internal palette
position - register number to set the color in, counted from 0.
color - pointer to a struct color which defines the color to set.
NOTE
This won't change anything onscreen, since the palette isn't updated
automatically.
SEE ALSO
MBS_RefreshPalette()
madblankersupport.library/MBS_Quit madblankersupport.library/MBS_Quit
NAME
MBS_Quit -- Signal that blanker task is about to exit. All screens
are closed.
SYNOPSIS
MBS_Quit();
void MBS_Quit (void);
FUNCTION
All allocated memory is flushed. Madhouse is told to start the next
blanker (if necessary).
NOTE
All screens and windows have to be closed at this time, blank mouse
pointer images and stuff like that are freed now, too.
WARNING
Don't call any other library function after MBS_Quit()!
madblankersupport.library/MBS_RefreshPalette
NAME
MBS_RefreshPalette -- Updates a screen's palette according to the
internal palette. (V26)
SYNOPSIS
MBS_RefreshPalette( palette, screen );
a0 d0
void MBS_RefreshPalette( APTR palette, struct Screen *screen );
FUNCTION
The given screen will get the palette information from the given
internal palette. You must call this function if you want to see the
changes on screen, which you have made with functions which don't
update the palette automatically (e.g. MBS_PutPaletteColor() or
MBS_PaletteSpread).
This is also useful if you have two screens with the same palette, as
the screen has to be defined here, again.
INPUTS
palette - pointer to the internal palette
screen - screen to set the palette on
madblankersupport.library/MBS_SetPaletteScreen
NAME
MBS_SetPaletteScreen -- connect the palette to your screen. (V26)
SYNOPSIS
MBS_SetPaletteScreen( palette, screen );
a0 d0
void MBS_SetPaletteScreen( APTR palette, struct Screen *screen );
INPUTS
palette - pointer to the internal palette.
screen - the screen that should be used together with your palette.
This function will store its Viewport and the amount of
colors used.
NOTE
HAM screens will fail.